• Eclipse Rich Client Platform (RCP) applications (desktop client only)
• Eclipse embedded Rich Client Platform applications
• Web applications
• Portlet applications (desktop client only)
• Database applications
• Messaging applications
• Web services applications

The toolkit provides wizards that enable you to create Client Services projects to develop client applications. The toolkit uses target definitions to provide a convenient method for you to specify the runtime environment, the build-time environment, and the set of components that can run on the platform.

For example, when you create a Client Services project, you select a target definition from a list of available targets, and then a set of features from a list in the target definition.

The toolkit uses this information to automatically set up the Java^TM build path and runtime for your project. You can then edit, compile, and debug your project. The toolkit provides a default list of target definitions; however, you can also create your own definitions.

Who should use the toolkit

Lotus Expeditor Toolkit is intended for use by developers of Java, Eclipse RCP, and J2EE. Using the provided tools, you can re-use your current skills and resources to deploy existing applications or to build new applications for your target runtime environment.

Prerequisites

A non-warranted and non-supported version of the Lotus Expeditor Toolkit is available for download from the developerWorks® Lotus Toolkits page. The downloaded file contains an update site that can be installed into an existing Eclipse 3.4-or-later-based Integrated Development Environment (IDE), including IBM Rational® Application Developer for WebSphere® Software V7.5.

If you are not already a customer of Lotus Expeditor, starting with the 6.2.1 release you can download and use the Developer Edition of the Desktop Client at no charge. This version of the Desktop Client is configured at install time for use as a development target of the Lotus ExpeditorToolkit.

You can download the Developer Edition and the Toolkit from the IBM Lotus Expeditor page on developerWorks.

At a minimum, Lotus Expeditor Toolkit requires Eclipse 3.4 with JavaSE 5.0+. For most functions, including the sample used in this article, you should also install the Eclipse Web Tools Platform (WTP), which can be installed from the predefined Ganymede Discovery site available in Eclipse.

If you do not already have a version of Eclipse and the Eclipse WebTools Platform installed, you can download and install the Java EE project bundle of Eclipse from the Eclipse Ganymede project page.

The Java EE project bundle and Lotus Expeditor Toolkit together provide everything needed for development of Java, Web, and Web services applications for Lotus Expeditor. Most application types can be created using just Eclipse Ganymede (3.4), WTP, and the toolkit.

If you create portlet applications, you need to install IBM Rational Application Developer V7.5. If you are not already a Rational Application Developer customer, you can download and install an evaluation version of the software.

NOTE: Prior to installing Lotus Expeditor Toolkit in Rational Application Developer, be sure to update to the latest fix pack of the Rational software.

Table 1 summarizes the necessary software.

Table 1. Required software

Application type or required function	Minimum prerequisite software for Lotus Expeditor Toolkit
Standard Java and Eclipse RCP and eRCP	Eclipse 3.4.2
Web Application Java, JSP, Servlet	Eclipse 3.4.2
Web Application Portlet container	Rational Application Developer 7.5.2 or IBM Rational Software Architect 7.5

Installing the target environment

The Expeditor Toolkit can be used to develop applications for Lotus Notes, Lotus Expeditor, Lotus Sametime® Connect Client, and Lotus Symphony. Releases of the toolkit prior to V6.2 included test environments for the Lotus Expeditor Client for Desktop and Lotus Expeditor Client for Devices product offerings.

These test environments were provided to facilitate the build and test of applications through the Lotus Expeditor Toolkit. However, with the 6.2 release of the toolkit, this is no longer the case. The appropriate client product offering must be installed before installing the toolkit.

For the purposes of this article, it is recommended that you install the Lotus Expeditor Desktop Client - Developer Edition. You can download the Developer Edition and the Toolkit from the Lotus Expeditor page on developerWorks.

To install the Developer edition, follow these steps:

1. On Microsoft® Windows® systems, run the setupwin32.exe program and follow the installation instructions.

2. On RedHat or Suse Linux® Enterprise Desktop (SLED) systems, run the installation by double-clicking the RPM and using the graphical RPM installer, or, alternatively, run the installer from the command line as follows:

rpm -Uvh

NOTE: The installation programs are in the desktop/install directory on the Client DVD.

3. To start the client, click the Lotus Expeditor Client shortcut on your desktop (on Windows systems) or in the Application > Office menu (on Linux systems).

Enabling the target environment for development

If you are using:

• either the Developer Edition of the Expeditor Client or using Lotus Notes as the target environment, you can skip to the Toolkit Installation section of this article.

• Lotus Symphony and Lotus Sametime, refer to their Software Development Kit (SDK)documentation for instructions on how to install their development enablement features.

• the standard version of the Lotus Expeditor Desktop Client, you must install the Desktop Development Enablement Utilities feature, which contains the following items:

- JavaDoc and .exsd files for public APIs in the client
- target definitions representing configurations that are supported for the client

Install the Utilities feature as follows:

1. Select File > Application > Install, to open the installation wizard.
2. Select the “Search for new features to install” option; click Next.
3. Select Add Folder Location. In the Browse For Folder window, browse to the platform update site on the Client DVD (in the desktop/updates/platform directory); click OK.
4. When the Edit Local Site window displays, click OK, and then click Finish.
5. When the Updates window displays, expand the updates/platform location, select the Development category containing the Lotus Expeditor Desktop Development Utilities feature, and then click Next.
6. Carefully review the license agreements for the feature. If the terms of the license are acceptable, select “I accept the terms in the license agreements.” Do not proceed to download the feature if the license terms are not acceptable.
7. Click Finish, to allow the download and installation to proceed.
8. After the feature is installed, you are prompted to restart Lotus Expeditor for the changes to take effect. Select Yes. The client closes and restarts.

Installing and configuring the toolkit

After you download the toolkit .zip file, unzip the file in a temporary location and, to access the toolkit installation instructions, open the index.html file in your browser of choice. Lotus Expeditor Toolkit is divided into two features in two categories, as shown in figure 1.

The Lotus Expeditor Toolkit category includes Lotus Expeditor Toolkit 6.2.1.20081020, and the device category includes Lotus Expeditor Device Toolkit 6.1.1.0-20081017.

Figure 1. Lotus Expeditor Toolkit V6.2.1 update window


The Lotus Expeditor Toolkit V6.2.1 feature contains the core tooling and should be installed by all developers. If you develop applications for devices, you should also install the Lotus Expeditor Device Toolkit V6.2.1.

For the purposes of this article (and follow-up articles), it is recommended that you install just the toolkit feature in the Lotus Expeditor Toolkit category. Follow the detailed instructions provided in the index.html file, or refer to the wiki article, “Installing the Lotus Expeditor Toolkit 6.2.1.”

After you install Lotus Expeditor Toolkit and restart Eclipse, the Lotus Expeditor Toolkit Configuration window displays (see figure 2).

Figure 2. Toolkit Configuration window


where the fields above are defined as follows:

Test Environment. To develop applications for Lotus Expeditor for Desktop, select the Lotus Expeditor for Desktop option.

Target Location. This is populated with the default location for the Lotus Expeditor Client for Desktop product offering. If you installed the client into an alternate location, use the Browse button to navigate to the correct location.

VM Name. This is also selected for you.

Compiler Compliance Level. Is set to 1.6 by default

If you want to develop applications for Lotus Expeditor for Devices, select Lotus Expeditor for Devices in the Test Environment field. This option is available only if you installed the Lotus Expeditor Device Toolkit feature and the Lotus Expeditor Client for Devices product offering.

The VM Name of the device Enterprise Edition (EE) is selected for you, and the Compiler Compliance level is set to 1.4.

NOTE:Windows XP is the recommended platform to use when developing for the Lotus Expeditor for Devices platform.

Test Environment Configuration Preferences. It's recommended that you select the “Display the first time a workspaceopens” option, so that the Configuration window is presented only the first time the toolkit is used in a workspace.

You can change this preference later in any workspace. When you click OK, the Eclipse IDE is reconfigured for development against Lotus Expeditor for Desktop.

Toolkit preferences

If you want to change the configuration of the toolkit later, do the following:

1. Access the configuration preference by selecting Window > Preferences > Client Services. On this page, you can reconfigure the environment to any of the other supported environments.
2. Click the Configure button and modify the IDE, using the same window as presented at startup.
3. After you save your changes, Eclipse is updated with your new selections.

Applications built to run on Lotus Expeditor must provide information to the platform about their contents through the Open Services Gateway Initiative (OSGi) manifest file. For more information on the OSGi manifest, refer to the "Creating manifest files" topic in the Lotus Expeditor Information Center

Lotus Expeditor Toolkit also provides the ability to automatically manage OSGi manifest dependencies. (For more information, read the developerWorks article, "Understanding how Eclipse plug-ins work with OSGi." ) The default setting automatically adds Import-Package statements into your manifest file as necessary.

If you want to use Require-Bundle statements for manifest dependencies, select the “Give preference to Require-Bundle” option and click OK. In general, the default selection of Import-Package is the most appropriate.

For additional details on the OSGi manifest, Require-Bundle, and Import-Package, refer to the "Class loading" topic of the Lotus Expeditor Information Center. You can modify the preference later, using Windows > Preferences > Client Services > Development.

Importing a sample

Lotus Expeditor Toolkit provides a large number of samples for both Desktop and Device applications. When you use Rational Application Developer, you can import the samples from the Help system. To do this, use these steps:

1. Select Help > Help Contents from Rational Application Developer. The Help is displayed in a new window.
2. Expand Samples in the left-hand Contents pane of the window. You'll see Showcase samples, under which are Lotus Expeditor samples and/or a Lotus Expeditor samples for Devices category; Application samples, and the Technology samples sections of the Samples Gallery as shown in figure 3.

Figure 3. Order entry sample in Rational Help system


3. Select the sample you want to import in the left-hand pane, and click the option Import the sample in the right-hand pane.

4. Let's use the Order Entry sample, available under the Showcase samples section, to demonstrate the launch capability; import that feature now.

5. When the Order Entry sample window displays, click Finish (see figure 4). The sample projects are imported into the workspace.

Figure 4. Order Entry Sample window



6. If you have configured Eclipse for use with the Device client, reconfigure the environment now for Lotus Expeditor for Desktop.

If you are using Eclipse and not Rational Application Developer, you can import the sample from the file system. To import the Order Entry sample using just Eclipse and the WTP, follow these steps:

1. Choose File > Import > General > Existing Projects into Workspace; click Next.
2. Choose the “Select archive file” option; click Browse.
3. Browse to \plugins\com.ibm.rcp.tools.samplegallery_6.2.1.\archive\orderentry.jar, and then click Open.
4. Verify that the check boxes next to all the projects have been selected, and then click Finish (see figure 5).

Figure 5. Import the Order Entry sample in Eclipse


The Order Entry sample is really two separate interface samples. The Order Entry Web sample is an example of a Web (JSP/servlet)-based application that can run locally on Lotus Expeditor Client. It requires either Rational Application Developer or Eclipse and the WTP to build the Web application.

The Order Entry sample also includes the Order Entry Rich Client sample, which shows an SWT-based user interface. The Rich Client version can be built and run using only the Eclipse SDK. The business logic used in the sample is shared between the Web and the Rich Client versions.

Launching

Lotus Expeditor Toolkit provides a custom launcher that can be used to launch Lotus Expeditor for Desktop, Lotus Expeditor for Devices, Lotus Sametime, and Lotus Notes.

1. Access the launcher via the Run > Run Configurations commands from the IDE menu. The launcher is named Client Services.

2. Select the Client Services launcher in the left-hand pane, and then click the New button. This creates a new instance of the Client Services launcher, as shown in figure 6.

Figure 6. Lotus Expeditor Toolkit Client Services launcher



3. The launcher is populated with all the options you need to launch your configured platform. Click the Run button to launch the client platform.

4. Lotus Expeditor Client is launched, and you are asked to create a new password if this is your first launch in the selected workspace; otherwise, you can enter your previously created password.

5. Start the Web version of the sample by clicking the Open button and choosing Order Entry Web Sample from the drop-down list. The starting page of the Web version of the sample displays, as shown in figure 7.

6. Click the Start button to begin using the sample application, and create a few new orders using the Web user interface.

Figure 7. Home page for the Order Entry Web Sample



7. Now start the Rich Client version of the sample by clicking the Open button and choosing Order Entry Rich Client Sample.

You then see the starting page of the Rich Client version of the sample. If you created orders in the Web version, you see these orders reflected in the Rich Client version as well (see figure 8).

Figure 8. Home page for the Order Entry Rich Client Sample


At this point, both the Web and the Rich Client versions of the sample are running. Because the two different applications share a common set of backend logic, orders that are created in one user interface are reflected in the other.

You can move between the two versions of the sample, creating new orders in each interface, by selecting the different application tabs at the top of the user interface.

A basic Order Entry Server is also provided as part of the sample. If you want to see the orders processed, refer to the Order Entry Sample instructions provided in the Help system or in the Information Center.

Toolkit projects

When you are ready to create your own applications, you can create projects using Lotus Expeditor Toolkit. The toolkit provides four different types of projects, which you can see by selecting File > New > Projects > Client Services category, from the Eclipse menu.

The four project types are the Client Services Project, the Client Services Web Project, the Client Services Portlet Project, and the Client Services Fragment Project (see figure 9).

Figure 9. Lotus Expeditor project types


The Client Services Platform and Client Services Target wizards let you create Platform and Target file definitions, respectively, in an existing project within your workspace.

The Wiring Properties wizard lets you create a Property Broker WSDL file in an existing project within your workspace. You can modify this file by using the Property Broker Editor component packaged with the Lotus Expeditor Toolkit.

Table 2 lists the recommended use of the project types.

Table 2. Project types and their recommended use

Project type	Suggested use
Client Services project	Basic Java code, user interfaces build from SWT and JFace, JDBC access, or other access to most Lotus Expeditor Java APIs.
Client Services Fragment project	Packaging of native code, platform-specific code, and translated material in properties, XML files, and so on.
Client Services Web project	Servlets, JSPs, Axis 1.4 Web service clients.
Client Services Portlet project	JSR-168 portlets; these projects are available only in Rational Application Developer when you install the Portlet tools.

Advanced options

In addition to the default configurations , there are other advanced configuration options for Expeditor Toolkit that you may find useful. Lotus Expeditor Desktop Client and Device Client are designed to be configured and installed in a number of custom configurations to meet your needs.

Lotus Expeditor Toolkit enhances the Eclipse concept of targets to allow you to simulate different configurations of the clients in your development environment to match the version installed on users' systems. When you configure Lotus Expeditor Toolkit for Desktop, the workspace target is set to the Default Target.

Two other configurations of Lotus Expeditor are provided for you to work with. The core target provides a subset of Lotus Expeditor that matches its minimum working set. The Default with Embedded Sametime Target allows you to launch Lotus Expeditor along with the embedded version of Lotus Sametime.

Figure 10 shows Lotus Expeditor Client running the Order Entry Rich Client sample along with the embedded version of Lotus Sametime in the sidebar.

Figure 10. Order Entry rich client sample with embedded Lotus Sametime in Lotus Expeditor


The target that is used can be selected in a few different places. To set the default for the workspace (that is, for new projects and new launch configurations), select Window > Preferences > Client Services > Development, and set the Default Target Selection as “Default with Embedded Sametime Target” as shown in figure 11.

You can also override the workspace default for each project; during the project creation process, you can select from any of the available targets in the system. To limit the choices, deselect those you don't need in the Select the Targets section, so they won't be available on the Development Preferences page (see figure 11).

Figure 11. Select the workspace default target


When you create a launch configuration, you can override the launch that's used by selecting the Targets tab of the launcher. You can use the Core target provided by the toolkit as a template to create your own custom configurations of Lotus Expeditor and to launch them from the toolkit.

To create your own target, import the Core target and use the Client Services target editor to add the features contained in your custom Lotus Expeditor platform. Refer to the "Creating a Target Definition" topic of the Information Center for more information on creating a custom target.

Conclusion

In this article, you reviewed the process for installing and configuring Lotus Expeditor Toolkit. You learned how to import a sample application and how to launch the application on the Lotus Expeditor Client for Desktop product offering. You also got a brief overview of the projects you can create with the toolkit. Finally, you saw some advanced features of the toolkit that you can use in developing applications for custom Lotus Expeditor platforms.

Resources

Download: IBM Lotus Expeditor V6.2.1:
http://www.ibm.com/developerworks/downloads/ls/lxpd/learn.html

developerWorks Lotus Expeditor page:
http://www.ibm.com/developerworks/lotus/products/expeditor/

Lotus Expeditor wiki article, “Using IBM Lotus Expeditor Toolkit 6.2.1 with IBM Lotus Notes 8.5.1”:
http://www-10.lotus.com/ldd/lewiki.nsf/dx/Using_IBM_Lotus_Expeditor_Toolkit_6.2.1_with_IBM_Lotus_Notes_8.5.1

developerWorks Lotus article, “Using IBM Lotus Expeditor Toolkit V6.1 with IBM Lotus Notes V8 and IBM Lotus Sametime”:
http://www.ibm.com/developerworks/lotus/library/expeditor-notes-sametime/

developerWorks Lotus article, "Getting started with the IBM Lotus Expeditor Toolkit V6.1.1":
http://www.ibm.com/developerworks/lotus/library/expeditor-toolkit/?S_TACT=105AGX01&S_CMP=LP

About the author

Pierre Carlson is a Senior Software Engineer based at IBM's Austin, TX, facility. He's the lead developer for the Lotus Expeditor Client and the architect of the Lotus Expeditor Toolkit, working with the Eclipse and OSGi technologies since before they worked with each other.

Pierre has been with IBM since 1998, working on a variety of products including printers, operating systems, network appliances, Web applications, software development tools, devices, and desktop runtime environments. He has degrees in computer science from the University of Utah and Texas State University.